                  Messaging Gateway LCR Propagation Sample

This sample sets up a "round-trip" propagation to illustrate both
outbound (AQ->TIB/RV) and inbound (TIB/RV->AQ) propagation of Oracle
Logical Change Records (LCRs). An outbound propagation job moves LCRs 
from the AQ queue MGWUSER.MGW_LCR_SRC to a TIB/RV subject. An inbound 
propagation job moves the LCRs from the same a TIB/RV subject to the 
AQ queue MGWUSER.MGW_LCR_DEST. The end result should be LCRs moved from 
MGWUSER.MGW_LCR_SRC to MGWUSER.MGW_LCR_DEST.

Note: This sample requires XDB and LCR packages installed.

Files 
----------
  create_users.sql
     Creates Oracle database users, MGWUSER, MGWAGENT, MGWADM needed for
     this sample

  create_queues.sql
     Creates AQ queues needed for this sample.

  create_conversion.sql
     Creates transformations between LCR and the canonical type 
     SYS.MGW_TIBRV_MSG_T for Tib/RV.

  lcr_adm_setup.sql
     Configures Messaging Gateway objects for propagating messages.
     This file must be altered by the user before it can be run.

  setup.sql
     Allows setup of this sample to be accomplished in one step. It calls
     create_users.sql, create_queues.sql, create_conversion.sql, and
     lcr_adm_setup.sql

  lcr_adm_cleanup.sql
     Removes the Messaging Gateway configuration for this sample.

  drop_conversion.sql
     Removes the transformations for this sample.

  drop_queues.sql
     Removes the AQ queues used for this sample.

  drop_users.sql
     Drops the Oracle database users used for this sample.

  enq_ddllcr.sql
     Enqueues a fixed DDL LCR into the AQ queue used as the source for
     message propagation.

  enq_rowlcr.sql
     Enqueues a fixed row LCR into the AQ queue used as the source for
     message propagation.

  deq_lcr.sql
     Dequeues a message from the AQ queue used as the destination for
     message propagation.


Configuring and running sample -- All files are SQL scripts
--------------------------------------------------------------
  1. Edit the script lcr_adm_setup.sql (or a copy).
     There will be a block that looks as follows:
        --
        -- WARNING!!!! The values below must be set before this script is run.
        --
        begin
          :gv_database         := '';
          :gv_tibrv_subject    := NULL;
          :gv_tibrv_username   := NULL;
          :gv_tibrv_password   := NULL;
          :gv_tibrv_subject    := 'oraLcr';
        end;

     Edit this block to include the appropriate values for these properties
     used for configuring a Messaging Gateway connection to Tib/Rendezvous. 

  2. As user, SYS as SYSDBA, run the script setup.sql to create the users
     MGWUSER, MGWAGENT, and MGWADM, create the AQ queues used by this 
     sample, and configure Messaging Gateway objects for propagating messages.

  3. As user, MGWADM (password MGWADM), start the Messaging Gateway agent.

     e.g.  exec dbms_mgwadm.startup;

     Check the MGW_GATEWAY view and the log file (in ${ORACLE_HOME}/mgw/log) 
     to determine the status of the Messaging Gateway agent.

     e.g.  select agent_name, agent_status from MGW_GATEWAY;

  4. As user MGWUSER (password MGWUSER), enqueue LCRs to the propagation 
     source queue by running the script enq_ddllcr.sql or enq_rowlcr.sql

  5. As a user MGWADM, check that the messages have been propagated

     e.g.  select job_name, propagated_msgs, failures from MGW_JOBS;

     This will show the number of messages that have been propagated for
     each propagation job since the Messaging Gateway agent was started.

  6. Dequeue the LCRs from the AQ queue by running the script deq_lcr.sql as MGWUSER.
     The script will return an error if no message is present or the message
     received is not a LCR.

Cleaning up the sample:
--------------------------------------------------------------
  1. As user MGWADM, before shutting down the Messaging Gateway agent, run
     the script, lcr_adm_cleanup.sql, to clean up the MGW configuration.

  2. As user MGWADM, shut down the Messaging Gateway agent.

     e.g. exec dbms_mgwadm.shutdown

  3. When the Messaging Gateway agent is shut down, if desired, run the 
     script, drop_conversion.sql, to remove the transformations and their
     funtions.

  4. When the Messaging Gateway agent is shut down, if desired,
     run the script, drop_queues.sql, to remove all AQ queues created 
     for this sample.

  5. Connect as SYS as SYSDBA and run drop_users.sql to remove Oracle 
     schemas created for this sample.
